/*
 * Copyright 2000-2011 Worth Enterprises, Inc.  All Rights Reserved.
 */
package com.worthent.foundation.util.state.provider;

import com.worthent.foundation.util.state.StateEvent;
import com.worthent.foundation.util.state.StateExeException;

/**
 * Specifies methods for pushing and popping the {@link StateTableData} maintained
 * by an implementation of {@link StateTable}. Implementations mix in this
 * interface to indicate they support stacking. Stacked state tables are often
 * useful for supporting recursive event processing such as parsing a recursive
 * data structure.
 * 
 * @author Erik K. Worth
 * @version $Id: StackableHistoryInstance.java 2 2011-11-28 00:10:06Z erik.k.worth@gmail.com $
 */
public interface StackableHistoryInstance {

    /**
     * Pushes a copy of the current <code>StateHistory</code> onto the stack so
     * that it can later be restored via the {@link #popStateHistory} method.
     * 
     * @param event the event that may be used to get the copy of the state
     *        history
     * 
     * @exception StateExeException thrown when there is an error pushing the
     *            state history
     */
    void pushStateHistory(StateEvent event) throws StateExeException;

    /**
     * Pops most recently pushed <code>StateHistory</code> off of the stack
     * using the result to restore the current state history in effect for the
     * state table instance.
     * 
     * @param event the event that may be used to identify the state history
     * 
     * @exception StateExeException thrown when there is an error popping the
     *            state history
     */
    void popStateHistory(StateEvent event) throws StateExeException;

    /**
     * Returns <code>true</code> if the history stack is empty and
     * <code>false</code> otherwise.
     * 
     * @param event the event that may be used to identify the state history
     *        stack
     * 
     * @return <code>true</code> if the history stack is empty and
     *         <code>false</code> otherwise
     * 
     * @exception StateExeException thrown when there is an error accessing the
     *            stack
     */
    boolean isStackEmpty(StateEvent event) throws StateExeException;

}
